= Contributing to Jenkinsfile Runner
:toc:
:toc-placement: preamble
:toclevels: 3

https://community.jenkins.io/c/contributing/jenkinsfile-runner/22[image:https://img.shields.io/badge/discourse-forum-brightgreen.svg?style=flat-square[Discourse]]
https://gitter.im/jenkinsci/jenkinsfile-runner[image:https://badges.gitter.im/jenkinsci/jenkinsfile-runner.svg[Gitter]]

This page provides information about contributing code to the Jenkinsfile Runner codebase.

== Getting started

1. Fork the repository on GitHub
2. Clone the forked repository to your machine
3. Install the development tools. To develop Jenkinsfile Runner, you need the following tools:
** Java Development Kit (JDK) 8.
     - We usually use [OpenJDK](http://openjdk.java.net/) but you can use other JDKs as well.
** Maven 3.5.4 or above.
** Any IDE which supports importing Maven projects.
** Docker.
** Make.

== Documentation

This page provides basic information about building and testing Jenkinsfile Runner.
In case you are more interested in details and in the architecture, see the link:/docs/developer/README.adoc[Developer Documentation].

== Contacts

If you have any questions or need help, please use the following channels:

* https://community.jenkins.io/c/contributing/jenkinsfile-runner/22[Forum on Discourse] - for JFR usage and developer discussions
* https://gitter.im/jenkinsci/jenkinsfile-runner[Gitter Chat] - for JFR usage and development questions
* https://www.jenkins.io/sigs/cloud-native/[Jenkins Cloud Native SIG] channels: mailing lists, chats, meetings
* https://groups.google.com/d/forum/jenkinsci-dev[Jenkins Developer Mailing list] - for JFR development questions

== Building

The build flow for Jenkinsfile Runner is built around Maven and Docker.

Run `mvn clean package` for the project to be just built and `mvn clean package -Denvironment=test` for the project
to be built and the integration tests to be launched, which are based on the https://github.com/jenkinsci/jenkinsfile-runner-test-framework[Jenkinsfile Runner Test Framework].

This will generate an assembly artifact through the `appassembler-maven-plugin` that can be configured and used to run Jenkinsfiles.

=== Building Docker images

This repository includes the base image which can be built simply as...

    docker build -t jenkins4eval/jenkinsfile-runner -f packaging/docker/unix/eclipse-temurin-11-jre/Dockerfile .

During development you can reuse the local machine build instead of doing a full build from scratch

    docker build -t jenkins4eval/jenkinsfile-runner:dev -f packaging/docker/unix/eclipse-temurin-11-jre/Dockerfile-dev-vanilla .

== Debugging

See the link:/docs/developer/DEBUG.adoc[Debugging Guidelines].

== Testing changes

Jenkinsfile Runner includes integration tests as a part of the repository.

These tests (`tests` module) take a while even on server-grade machines.
All of them will be launched by the continuous integration instance,
so there is no strict need to run them before proposing a pull request.

In case you want to run them, see the previous section. You could also enter the `tests` directory and execute the `make` command.

== Proposing Changes

All proposed changes are submitted and code reviewed using the _GitHub Pull Request_ process.

To submit a pull request:

1. Commit changes and push them to your fork on GitHub.
It is a good practice to create branches instead of pushing to master.
2. In GitHub Web UI click the _New Pull Request_ button
3. Select `jenkinsci/jenkinsfile-runner` as _base fork_ and `master` as `base`, then click _Create Pull Request_
4. Fill in the Pull Request description according to the changes.
5. Click _Create Pull Request_
6. Wait for CI results/reviews, process the feedback.

It is recommended that new features/changes include testing proving the changes are working correctly.

== Continuous Integration

Jenkinsfile Runner uses https://ci.jenkins.io[ci.jenkins.io] as Continuous Integration server and uses Jenkins Pipeline to run builds.
See the job https://ci.jenkins.io/blue/organizations/jenkins/Tools%2Fjenkinsfile-runner/[here].
The code for the build flow is stored in the `Jenkinsfile` in the repository root.

If you want to update that build flow (e.g. "add more checks"),
just submit a pull request.
